Publishing a Custom Go GitHub Action

Open source software is not only about having access to free software but also about giving back to the community. We are going to learn how to give back to the GitHub Actions community through publishing an action to GitHub Marketplace. This will enable the entire user community of GitHub to benefit from it.

In this lesson, we will learn how to publish a custom action to the GitHub Marketplace. We will learn the basics of publishing actions. After covering the basics, we will learn how to automate versioning for a published action. We will learn how to use the tweeter action to tweet an announcement of new releases to tweeter. Finally, we will learn how to publish our action to the GitHub Marketplace so that it can be used by the rest of the GitHub community across the world.

The basics of publishing actions#

Publishing an action to the GitHub Marketplace adds some requirements and best practices that, for a local action, as we built in the previous section, do not apply. For example, the readme for the repository will be the landing page for the action in the marketplace, so we'd want to provide a description and usage guidance for the repository readme.

The following are the requirements for publishing an action to the GitHub Marketplace:

• The action must be in a public GitHub repository.

• In the root of the repository must be a single action named action.yaml or action.yml.

• The name of the action in action.yaml must be unique to the marketplace. The name may not overlap with any GitHub features or products, or any other names that GitHub reserves.

• A public action should follow v1 and v1.2.3 semantic version guidance so that users of the action can specify a full semantic version, or simply v1 to denote the latest in the v1 major semantic version series.

Goals for publishing the tweeter custom action#

The following are goals for publishing the tweeter custom action:

• Set up a release-triggered workflow that will handle semantic version management.

• Publish the tweeter action to the GitHub Marketplace.

Managing action semantic versioning#

The first and second goals of publishing the tweeter custom action to the marketplace are as follows:

• Set up a release-triggered workflow that will handle semantic version management.

• Use the action to tweet an announcement of the new release of the action.

We are going to build a workflow to update the major version tag—for example, v1—to point to the latest release in the v1.x.x series of semantic versions. The workflow will also be responsible for creating new major version tags as new major semantic versions are released:

The preceding workflow does the following:

• Triggers on a release being published or on a manual UI submission. This means that a project maintainer can trigger the workflow via the GitHub UI if ad hoc execution is required.

• Declares that the workflow requires rights to write to the repository. This is used to write tags.

• Declares the TAG_NAME environment variable, which is either the ad hoc job input or the tag of the release.

• The update_tag takes the tag in v1.2.3 format and updates the tag's major semantic version tag to the latest version within that major semantic version. For example, if the new release tag is v1.2.3, then the v1 tag will point to the same Git ref as v1.2.3.

• Clones the source code using actions/checkout@v2.

• Tweets about the new release using Twitter developer credentials embedded in GitHub repository secrets. To set up Twitter developer credentials, go to the Twitter developer portal and set up an account and application. After we gather the secrets, we can add them to the repository secrets under the “Settings” tab, as shown in the following screenshot:

With the preceding workflow, when we apply a tag – for example, v1.2.3 – the repository will also be tagged at the same Git ref with v1. After the tags are set, the tweeter action will execute, announcing the release to the world.

Recall from the previous section that when we tag the tweeter repository with a semantic version, the release workflow will trigger, causing a new release to be created. This workflow will then trigger the action version update release workflow, which will tag the action with the major version and announce through Twitter that the action release is available.

All that is left to do is to release the action to the GitHub Marketplace. This only needs to be done the first time the action is released.

Publishing the tweeter action to the GitHub Marketplace#

The final goal of publishing the tweeter custom action is to publish the tweeter action to the GitHub Marketplace. The first publication of our GitHub Action is a manual process and can be accomplished by following this guide on GitHub. After taking this first set of manual steps, they will not need to be repeated for future releases.